Docs
Quickstart, guides and the canary.yml reference.
From zero to a preview in one pull request.
Install the CLI, let it write nine lines of canary.yml, and push a branch. The rest of this page is for the day you need more than that.
Three commands and a pull request.
The CLI reads the Compose file or chart you already have and writes the first canary.yml for you. After that, Canary listens to the repository.
-
brew install
Install the CLI
One binary for macOS and Linux. Sign in once with canary login and it keeps the token in your keychain.
-
canary init
Describe the stack once
It finds your Compose file or chart, asks where the database comes from, and writes canary.yml beside it.
-
git push
Open a pull request
Canary builds the branch, comments with the link, and tears the preview down when the pull request merges.
- brew install canary-run/tap/canary
- canary init
- found docker-compose.yml: web, api, worker
- found postgres@16, seeding from snapshot://nightly
- wrote canary.yml (9 lines)
- git push -u origin feat/multi-currency
- canary open
- building #482 from 9f3e1b0 ...
- pr-482.northwind.canary.run is live (3m 41s)
Guides, by what you are doing.
Written by the engineers who built each part. Every one ends with the canary.yml that does it.
-
Get started
Install the CLI and get a first preview from a repository you already have.
5 min
-
Every key, its type, its default and what it changes.
12 keys
-
Source control, build files, databases, clouds and secret stores.
15 integrations
-
Data
Deterministic replacement that keeps joins and unique indexes working.
7 min
-
Operate
What is kept while a preview sleeps, and what counts as a preview-hour.
6 min
-
What is removed on merge, in what order, and the record it leaves.
6 min
-
The arithmetic for a first cap, and what happens when you reach it.
6 min
-
Review
A ten-minute checklist for designers, QA and product.
6 min
-
Security
What stays in your cloud, and the two things that are sent to Canary.
SOC 2 Type II
-
Six signed events, and the endpoints that return the same objects.
HMAC-SHA256
Looking for something that is not here? Ask an engineer
canary.yml, key by key.
Every key is optional except preview.from. The file is read from the branch being built, so a pull request that changes it previews the change first.
preview.from
path
required
path · required The Compose file or Helm chart that describes the stack.
preview.services
list
all
list · all Which services to build. Leave it out and every service in the file is built.
preview.values
path or map
none
path or map · none Helm values layered over the chart's defaults for every preview.
database.engine
string
from the file
string · from the file The engine and major version to restore into, such as postgres@16.
database.seed
uri
empty
uri · empty Where the data comes from: snapshot://nightly, a dump in the repo, or nothing.
database.mask
list
none
list · none Columns replaced before the snapshot leaves its bucket. JSON paths are allowed.
secrets
string
test
string · test The secret set a preview may read. Production sets are refused.
access
string
workspace
string · workspace Who may open the link: link, workspace or password.
sleep_after
duration
30m
duration · 30m Idle time before a preview is frozen to disk. Use never to keep one warm.
teardown
string
on_merge
string · on_merge When a preview is removed: on_merge, with an hour's grace on close, or on_close.
review.comments
boolean
true
boolean · true Lets reviewers pin comments to the page and posts them to the pull request.
budget.monthly_usd
number
no cap
number · no cap The workspace's spend cap. At the cap, previews sleep and new ones wait.
Validate a file before you push with canary check.
Stuck on a build? Send us the log.
An engineer reads every message, usually within the hour during the US working day. Or start with a repository and see how far the defaults get you.
